All plugins go in the the Plugins folder, with the exception of channel JOIN/PART scripts, which go in the 'JOIN' and 'PART' folders in the Plugins folder. You may name files anything you want, as long as they don't start with a * (reserved for non-plugin files that go in the plugins folder).
ShadowBot accepts three types of commands in scripts: configuration commands, flow commands and bot commands. Flow commands are always preceded with an @ (i.e., "@LABEL thelabel"), bot commands are not preceded with anything (i.e., "SAY Hello!"). The third type of commands, configuration commands, are preceded with a *. When parsing plugin files, any line begining with a a ' (comment character) or a * (after the inital parsing for configuration commands) is ignored.
All of ShadowBot's commands may be used from plugins. When ShadowBot's command parser is called by a plugin, it executes commands with a security level of 1001 and a protection level of 5. (So scripts can do *anything*. It is YOUR responsibility to check for proper access.)
Flow Control Commands
@LABEL <theLabel>
Defines a label that is used with the IF and GOTO commands. Labels are case sensitive and have a maximum length of 31 characters. Labels MAY NOT start with the character '>'.
@ENTRY <commandName>
Defines a label which can be used to put multiple scripts into one file. For example, if you put two scripts in one file, commands "hello" and "goodbye," execution will start from the top unless you include the commands '@ENTRY hello' (for hello) and '@ENTRY goodbye' (for goodbye). These have a maximum length of thirty characters, so anything past this is not significant.
@GOTO <theLabel>
Moves script execution to the label specified. If you try and jump to a label that doesn't exist, an error will be displayed in the console and execution will stop.
@END
Stops script execution. If this is not the last line in your script, the last line will not be executed.
@@END
Makes ShadowBot stop parsing the file. Useful if you want to put comments at the end of a file. Also functions as an @END.
The most powerful of the flow control commands, IF allows you to do logic branching.
Valid IF commands:
ACCESS - integer - use for access level checking
NICKPRESENT - string - use to check to see if someone is in the channel
NICKHASOPS - string - use to see if someone has ops
FOUNDUSER - boolean - use to see if the user was found in the userlist
AUTOOP - boolean - use to see if the user has autoops. (this also checks foundUser and
returns false if founduser is false)
You can also do string comparisons by enclosing a string in quotes, and number comparison by preceding the first number with a #.
Valid data types:
integer - any real whole number
string - any text, 255 or less characters (see note at bottom)
boolean - true or false, denoted by the text 'TRUE' and 'FALSE'. NOTE: anything other than 'TRUE'
is assumed to be 'FALSE'.
Valid operators:
operator meaning use with note
< less than int, str 1
> greater than int, str 1
= equal to int, str, bool 2
== exactely equal to str 3
<> not equal to int, str, bool
<= less than/equal to int, str 1
>= greater than/equal to int, str 1
=~ match with mask str 4
Notes:
1- for boolean comparison, always returns FALSE.
2- for string comparison, case is not sensitive.
3- for string comparison, case is sensitive.
4- for boolean and integer comparison, operates as =.
Branching: the <goto> and <else goto> parameters
If the contition in the IF command is true, execution jumps to the label specified by the <goto> parameter. If <else goto> is specified, execution jumps there if the IF statement is false, otherwise it continues on the next line.
You can use the variables in the Script Variables file in IF commands.
Examples:
@IF NICKPRESENT = $ARG1 nickFound nickNotPresent
If the nick passed by the first parameter passed to the plugin is on the channel, execution jumps to nickFound, otherwise it goes to nickNotPresent.
@IF ACCESS < 400 noAccess
If the access is less than 400, jump to label noAccess, else continue execution with the next command.
@IF "string 1" = "string2" true false
If string one and string two are the same, (case not sensitive)...
If the userhost of the person who activated this script matches the mask dshadow@*.umd.edu, then true...
Other Scripting Commands
@SET <variable> <value>
Allows you to change a variable. You must define variables before you use them.
@ADDONE <variable>
@SUBONE <variable>
These commands add/subtract one from the specified (integer) variable.
@DELAY <numTicks>
Pauses execution for numTicks ticks. (A tick is 1/60 of a second.)
@WRITELN <theMessage>
Copies the message to the console.
@BEEP
Makes your computer beep.
@GETARGS <numArgs>
Causes ShadowBot to process the command's arguments. Returns the number of arguments found (equal to or less than numArgs) in the variable $NUMARGS.
Example:
!command arg1 arg2 arg3 arg4
@GETARGS 3
$ARG1 = 'arg1'
$ARG2 = 'arg2'
$ARG3 = 'arg3 arg4'
$NUMARGS = 3
@GETARGS 5
$ARG1 = 'arg1'
$ARG2 = 'arg2'
$ARG3 = 'arg3'
$ARG4 = 'arg4'
$NUMARGS = 4
The Bot commands SAYQ, MSGQ, and NOTICEQ may be of special interest to plugin writers. They function like SAY, MSG, and NOTICE, but don't display text in the console or channel windows in ShadowBot.
NOTE: Lines have a 255 character limit; this includes any variables that are expanded.
